Guidelines: Rational Unified Process Styleguide
Topics
The Rational Unified Process Styleguide describes the conventions to use when developing the Rational Unified Process online and is organized in these subsections:
The style of the process site is enforced by theme, style sheet, and templates all of which are covered in the following subsections, along with some additional style issues.
Use these guidelines to keep a uniform look throughout your documentation. If applying them in a given situation looks strange or confusing, skip the guideline and use common sense.
Cascading Style Sheets 
Each page is linked to a Cascading Style Sheet. The style sheet for Rational Unified Process is located at the top-level folder of the Rational Unified Process. To link the style sheet file to a page, the following line must be included in the header, which is the section between <head> and </head>:
<link rel="stylesheet" href="../../rop.css" type="text/css">
The path given above assumes that rop.css is located in the Parent-Parent folder. Adjust according to your actual relative path.
The Rational Unified Process templates have a link to the rop.css file already. In most cases Microsoft FrontPage« manages to figure out the relative path once you save the new file in your file structure. If, for some reason, it doesn't work, edit the HTML code appropriately.
There is a potential for overlapping between the theme and the style sheet. However, Rational Unified Process does not use the Microsoft FrontPage« theme.
In the style sheet, there are so-called classes defined for different HTML markups. When a file linked to a style sheet is loaded in the FrontPage editor, the style list displays the classes from which you can choose.
Updates to the style sheet are immediately reflected without any changes in the actual files. Sometimes the FrontPage editor does not register the change, however, a web-browser will once you reload.
Information on syntax and other details for style sheets is found in Cascading Style Sheets.
Style Classes for the Rational Unified Process
| Banner headings | Heading 1.banner and Heading 2.banner Puts a blue background under the text. |
| Example heading | Heading 5 (H5) This should say "Example:". |
| Example | Indent using the "Increase indentation" button, next to the buttons for bulleted list and numbered list, or use Normal.example. |
| Picture text | Normal.picturetext |
| Definition | Normal.definition Used for definitions of modeling concepts. Do not use the predefined Definition for this purpose. |
| Table heading | Normal.tableheading Give table headings a bolder appearance. |
| Table text | Normal.tabletext Adjusts text to the left in tables. |
| a,b,c lists | Numbered List.alpha. Note that the FrontPage editor doesn't show the alpha characters, however, you can see them in the preview pane and in a "real" Web browser. |
| Bullets and Numbers | For bulleted and numbered lists, use the predefined Bulleted List and Numbered List. |
| Plus and Minus bullets | Bulleted List.plus and Bulleted List.minus Uses a plus or a minus sign for bullet. |
Different Browser Support
Microsoft Internet Explorer 4.0 supports all the style sheet features used in the Rational Unified Process.
Netscape Navigator 4.04 and 4.05 show the following signs that indicate a lack of support:
|
Defaults to red instead of the specified electric blue. |
|
The margin-specifier is ignored. To work-around, set table width to 85% if it's wider than the text and center alignment. |
|
No special bullets appear; that is, the specifier "list-style-image" is ignored, therefore regular bullets, and plus and minus bullets, do not show up. Default bullets are used. |
|
Lists with letters instead of numbers turn out as numbers. (Style Numbered List.alpha) |
|
The blue heading banners don't stretch all the way across, which is a cosmetic problem. |
Theme
Rational Unified
Process does not use the Microsoft FrontPage« theme.
A theme governs navigation buttons, bullets, background, link colors, font styles, and sizes for regular text, headings, and more. Here are some of the features and disadvantages:
- One of the strengths with themes is that Microsoft« FrontPage« supports creating and laying out navigation buttons and page banners. This is done using the navigation view information. However, Rational Unified Process does not use this feature. Other features with themes can be implemented with cascading style sheets and, because we aren't using the navigation bar feature, we can rely entirely on style sheets. See Cascading Style Sheets above, under the heading Different Browser Support for some of the problems experienced with Netscape Navigator.
- Bulleted lists composed with a theme in place are actually implemented using tables rather than the HTML unordered list tag <UL>. When migrating to Microsoft Word«, bulleted lists are converted to tables with images instead of bulleted lists. Another problem is that indenting text with style sheets does not work for bulleted lists.
- Themes are proprietary to Microsoft and are not an adopted standard, whereas style sheets are a standard. Netscape Navigator and Microsoft Internet Explorer show different things in some instances; for example, table borders show in Navigator when the theme dictates they should be white, that is, invisible on a white background.
- It's unclear how themes and style sheets work together.
- Opening HTML pages with a theme causes some Word installations to crash.
- When updating a theme, as well as a shared border, all files are visited, which means that all files must be checked in and the baseline frozen every time this is done. Style sheet updates do not affect any other files.
If you are using a Microsoft FrontPage theme
A FrontPage theme can be edited using the Theme Designer, which can be installed from the FrontPage CD.
It takes quite some time to re-apply a theme to a site of this size, because every file is visited. This means that all files must be checked out when re-applying a theme.
Theme files are kept in the Themes folder of the FrontPage installation folder.
The sizes of the different buttons
To maintain compatibility with pre-defined themes, FrontPage dictates certain sizes for theme button images. If your buttons have other sizes, things will move around when you apply another theme. Although the current theme does not follow these guidelines, here are the required dimensions:
| Global navigation | 95 x 20 pixels |
| Horizontal and vertical navigation | 140 x 60 pixels |
| Up, Home, Next, Previous | 100 x 20 |
| Banner | 600 x 60 |
The actual image can be smaller than specified, but the bitmap needs to have the above dimensions.
Templates
When creating a new page, there are templates to get you started and help you stay with the style of the site. These templates need to be installed in the FrontPage Pages folder.
- Copy the folders inside the Templates/fp_25/ folder.
- Paste these folders into the Pages folder of your FrontPage installation
folder; for example,
C:/Program Files/Microsoft FrontPage/pages. The Rational Unified Process template folders should end with .tem and be at the same level as the other template folders. - In the FrontPage editor, choose File->New.
- From the list of templates, select the one you want. The Rational Unified Process templates are named "RUP xxx".
See the Authoring Web Pages.
Top
In order to quickly return to the top of a page, place a top bookmark there and, after each major heading, add the top-arrow with a link to the top.
- If there are top-arrows with links to the top, the easiest way to add another is to Copy, then Paste it.
- If not, here is the procedure:
- Place the cursor before the title.
- Choose Edit->Bookmark... and write "Top" in the name field.
- Check to make sure it isn't already included in the list. If it is, make sure it's placed before the title. Click OK.
- Copy this icon .
Yes, we mean this icon right here.
- Paste the icon after the heading. Add a space between the icon and the heading text. Make sure the link to #Top was copied correctly too by moving the mouse over the icon and checking the status bar. It should say #Top.
Bullets
Be consistent using uppercase or lowercase letters, periods, and commas within a set of bullets. Use the style best suited for the information.
Use bullets to list an unordered series of items other than a sequence of events or steps.
Example: Full sentences
- Begin each bullet with a capital letter.
- End each bullet with a period, question mark or exclamation mark if it's a full sentence.
- This is the preferred style and it's especially important for check points and longer bullets.
Example: A comma-separated list
- each bullet begins with a lower case letter,
- ends with a comma,
- it's the next to last bullet with either ", or", ", and" or something similar, and
- the last bullet ends with a period, question mark, or exclamation mark.
Use a comma-separated list where:
Example: Simple list
When you have a list of concepts, names, and so on, begin each bullet with a lower case letter. Don't use any commas, periods or other punctuation. For example:
There are four different models in the Rational Unified process:
- use-case model
- design model
- implementation model
- test model
Numbered lists
Use numbered lists for ordered lists, such as a sequence of steps. Let each item be a full sentence.
Alpha lists
Use style Numbered List.alpha to create an ordered list with a, b, c, ... This type of list is used if you'll be referring to any of the items in other text; for example, see item a. above.
Italics and Bold
Use bold to emphasize. Do not use italics. Italic fonts are hard to read online and may not work correctly in all Web browsers.
Chapter and Section Numbering
Whether to number headings or not is still a debate. Customers have requested a way to easily and uniquely reference sections of the material. Because of the dynamic nature of hypertext, numbered headings are difficult to interpret because the headings may be displayed outside of the context of the numbered document. To avoid confusion, use unique names for section headings and fully qualify section references using the name of the page as well as the name of the subsection if it's ambiguous.
Where you must number, such as in brief outlines for documents, use the following convention:
1 Heading level 1 (three spaces between the number and the heading title)
1.1 Heading level 2
1.1.1 Heading level 3
Heading level 4 - 6 (no numbering)
Heading levels deeper than 6 are not used.
An appendix is named using letters: Appendix A, Appendix B, Appendix C, and so on.
Examples
Normal.example
Examples described separately from the body text should have the Normal.example style. Of course things can be exemplified directly in the body text as well.
Every text with the Normal.example style should be preceded by a line with the text "Example:" as a Heading 5 (H5).
Title Banner
In the Rational Unified Process, we do not use the FrontPage component for page banners. One reason is that they require updating in the Navigation View, which is a central file. Another reason is that we do not need the Navigation View for anything else, such as navigation bars, and it leaves one less thing to worry about.
What do we use? There are two styles in the style sheet for the top title:
Heading 1.banner
and
Heading 2.banner
Heading 1.banner is used in major workflow chapters and other big titles having few words. Heading 2.banner is used for all objects in the process, because these usually have long names; for example, Activity, Worker, Guideline. The templates show when they are used.
Unfortunately Netscape Navigator« and Microsoft Internet Explorer« treat background color for text differently. Internet Explorer colors the entire line from margin to margin, whereas Navigator only colors the area occupied by the text.
Banners, Navigation View, and HTML tag <title>
If you use the Navigation View and the FrontPage component for the banner, this might be good to know:
- If the page exists and you drop it into the Navigation view, it will get the title, as specified, with the HTML tag <title>. This is just a copy and there is no magical relationship between these two titles. Updating the page name in the Navigation View will not update the title in the <title> tag. Changing the page title will not update the banner either, unless you remove the file from the Navigation view and add it again, but it's just as easy to edit the name.
Pictures
- Pictures and tables are centered in the text column.
- Pictures in tables are left-adjusted or centered.
- Do not use frames around the pictures. With hyperlinked pictures, set border width to zero in Image properties.
- Keep pictures small. The maximum width for a picture is 12 cm.
- Download all pictures in CorelDraw format from the Rational Unified Process Resource Center.
Printed documentation
For pictures that go into printed documentation as well as online, do not use bitmaps. The exception to this rule is screen dumps. CorelDraw is used to draw the diagrams in the Rational Unified Process, which are exported from the CorelDraw format to the GIF-format.
When creating printed documentation, the original CorelDraw picture is inserted into the proper chapter in Microsoft Word.
Some pictures are smaller than the minimum size CorelDraw allows for exporting to GIF. These may need a CorelDraw version, as well as a separately made bitmap version. See the section titled "CorelDraw tips" for more information..
Small images for online only
Icons, bullets, buttons, and so forth used only for online documentation can be created with a bitmap paint tool such as Image Composer, which comes with FrontPage, or CorelPaint. Adobe PhotoShop is also a current favorite. All of these tools require some experimentation to become familiar with them. Export pictures as GIF files. CorelDraw has a minimum size for exporting GIF files and, if it's not small enough, you have to scale the picture, which usually gives an ugly result.
If icons are to be included in the printed version too, you'll need corresponding CorelDraw icons for them.
CorelDraw tips
This is not meant to replace the CorelDraw manual, but solely to share experience.
- Reuse similar pictures when creating new ones.
- Bezier curves and lines can be copied and pasted, then easily reformed. You get the same line thickness and type of arrow head. Experiment with Bezier curves as they're easy and fun to use once you get the hang of them. Double clicking on a node to open a tool box allows you to remove and add new nodes.
- You'll want to group icons with their text to create easy-to-move picture elements. Remember to adjust icon and text; for example, center text under workers and activities. Reusing groups for icons and text will preserve the distance between the icon and the text, creating a uniform look to the whole picture.
- The font style and size for text under all icons should be in Arial bold 10pt.
- If you round the corners of rectangles, out-of-proportion scaling will also change the roundness of the corners. It is better to draw the rectangle in the approximate proportions you want it before rounding the corners; for example, swim-lanes in workflow diagrams.
- Adjust and distribute the picture elements to each other when you're done to avoid time-consuming, unnecessary adjusting.
Exporting to GIF from CorelDraw
To export a picture to GIF, follow this procedure:
- Select the entire picture. It's a good idea to group it.
- From the right mouse button menu or File menu, choose export.
- In the displayed dialog box, name the GIF file. Type the extension .gif with lowercase letters to make sure you get lowercase letters because UNIX servers are very picky with case and it's important to keep it uniform. Check the box for exporting only the selection.
- On the next dialogue that displays, specify:
- Color: 256 colors
- Size: one-to-one
- Resolution: 75 dpi
- In the final dialogue that displays, specify:
- 89a-format
- Check interlaced if you want; the picture loads with stepwise finer resolution
- If relevant, choose a transparent color. This is usually white, index 215 in the default palette
Reusing pictures in many places
You can reuse a picture, even hotspot pictures, by placing them in an HTML-file by themselves then include them where you want them. This is useful for pictures that appear in more than one place.
- Choose Insert->FrontPage Component....
- Select Include Page.
- Specify the URL.
- Click OK.
Hotspot Pictures
It's very easy to create hotspots in pictures in FrontPage.
- Select the picture you want hot spots in and a picture toolbar appears.
- Mark the hotspots with the hotspot area tools, which are to the left in the toolbar.
- The displayed dialog asks for the URL to which you want to link the hotspot. You can double-click on hotspot areas to edit them.
- Once you deselect the picture, the hotspot frames become invisible.
Using Colors
First of all, colors take up lots of spaceùthink twice before using them!
Web browsers use 216 colors from what is known as the color cube. Using the RGB scheme, the 216 colors are made up from a triplet of {00, 51, 102, 153, 204, 255): in hex that is {00, 33, 66, 99, cc, ff}. These ones are already in CorelDraw's standard palette.
We use a subset of these colors to keep the online version harmonious from a color standpoint. In the picture below, you can see the colors in our subset, and how they're used. As you may notice, we aren't using all of them yet. The names of the colors are shown to help you choose the right ones in CorelDraw. The RGB value is also indicated.
There is a custom palette, with the colors below as well as black and white, that you can use as follows:
- Download the palette file rup_palette.cpl. You might want to save it in the Corel installation folder, where the pre-defined palette files reside. In Corel8, it's in the Custom folder.
- In CorelDraw, right-click the Color Palette's border, then click Open.
- Choose the drive where the template is stored from the Look In list box. Color palettes have the extension .CPL.
- Double-click the folder where the file is stored.
- Double-click the palette's file name.
Tables
For headings in tables, use the style Normal.tableheading.
The theme rules that there should be no borders around tables. In fact, they are there, but they're white. If you really want visible borders, override with local settings.
Table placement
- Tables are centered in the text column.
Text alignment in cells
- Vertical alignment should be Top.
- Horizontal alignment should be Default.
References
A "thing" is a worker, artifact, guideline, activity, and so on. A "thing page" is a page with an activity, worker, artifact, guideline, and so forth.
|
Kind of references |
Examples |
Comment |
| To a 'thing page' | ...bla bla bla, see Activity: Find Use Cases and Actors. | Alt 1: In the text. |
| ...yada yada (see Guideline: Use Case), yada yada | Alt 2: In parenthesis. | |
| To a section in a 'thing page' | ...bla bla bla, see section "Timing" in Artifact: Software-Architecture Document. | Hyperlink to a page. The user is supposed to find the section. |
| Hyperlink references to a chapter in a manual. | ...yada yada yada, see the section titled Overview in "Rational Unified ProcessùAn Introduction". | The manual within quotation marks. |
| Non-hyperlink references. | ...yada yada yada, see the section titled "Overview" in "Rational Unified ProcessùAn Introduction". | The section within quotation marks, the manual in quotation marks. |
| In-text reference (preferred alternative) | ...Another technique is to perform role playing. See Role Playing, in which people act as business actors, business workers, and business entities. |
|
| In-text reference (second alternative) |
...Another technique is to perform role playing, in which people act as business actors, business workers, and business entities. | Warning: Avoid this style of reference. |
General guidelines for cross-references are provided here:
- In the tables:
Create hyperlink to the thing with no prefix, such as Use Case.
Do not have the prefix, such as Artifact: Use Case. - Do not mention the process when we reference as a "thing" in the
process.
Write 'see Activity: Use-Case Analysis'.
Do not write 'see Rational Unified Process - Activity: Use-Case Analysis'. - Avoid referencing a bookmark in another page. Use the style recommended above for references "To a section in a page". Of course, this requires that the named section ( called "Timing" in the example) is visible on the page. Otherwise you may consider a reference to a bookmark. There is also a problem that FrontPage doesn't support bookmarks very well.
Return and Shift-Return (Vertical White Space)
- A return means make a new paragraph. In HTML you will get a <p>-tag or some other tag indicating a block of some sort. Usually, this is what you want.
- A shift-return only inserts a new-line in the current paragraph, whereas
in HTML a <BR>-tag is inserted. The shift-return is useful when:
- a return gives you more vertical white space than you want; for example, an outline description
- you want to control where the line breaks in a bulleted list or in any paragraph for that matter
File Naming
File names should be no more than 20 characters long and should contain only alphabets, numbers, and underscores (_). Spaces and most symbols such as &, *, ; should not be used. It is also highly recommended that all file names be named using lowercase letters.
The current file naming convention uses the abbreviations listed in the following table, and an abbreviated name of the file contents, separated by an underscore. For example, the artifact Use-Case Model is called ar_ucm.htm and the modeling guideline for the Use-Case Model is md_ucm.htm.
We are considering a different way to name files to accommodate the requirements of unambiguous page referencing. Customers have expressed a need to reference items in the process in an easier way and it makes sense to use the same numbering or code in the file name, or at least some sort of obvious mapping.
| Concept | Abbreviation |
| concept | co_ |
| activity | ac_ |
| worker | wk_ |
| artifact | ar_ |
| report | re_ |
| workflow introduction | int_ |
| workflow detail | wfs_ |
| workflow graph | wfsg_ |
| iteration workflow | iwf_ |
| guidelines (for models, model elements, and artifacts) | md_ |
| work guidelines | wg_ |
| check lists | ck_ |
| manual pages | im_ |
| overview | ovu_ |
| examples | ex_ |
| Word templates | wd_ |
| SoDA templates | so_ |
| HTML templates | wb_ |
| guideline overviews | mdov_ |
| introduction manual | im_ |
| tool mentors | tm_ |
Microsoft Word template
There is a Word template for creating manuals in print called rup.dot. We suggest that you create a separate folder for Rational Unified Process Microsoft Word templates named, for example, "RUP" in Word's template folder, which is typically C:\Program Files\Microsoft Office\Templates. Place a copy of this template file and others there. For more information on using Word, see Working in Microsoft Word to find out how to, and how not to, use Microsoft Word for HTML authoring.
Index Online
See The Rational Unified Process Tools User Guide for information on how to generate an index.
See the KeyWordIndex
for more information on how to enter keywords into Rational Unified Process
pages.
